﻿using System;
using System.Globalization;

namespace lucere.service.search
{
	///////
	/// Stores information about how to sort documents by terms in an individual
	/// field.  Fields must be indexed in order to sort by them.
	////
	public interface ISortField : IEquatable<ISortField>
	{
		///<summary>
		/// Returns the name of the field.  Could return <code>null</code>
		/// if the sort is by SCORE or DOC.
		/// <returns>Name of field, possibly <code>null</code>.</returns>
		///</summary>
		string Field { get; }

		///<summary>
		/// Returns the type of contents in the field.
		/// <returns>One of the constants SCORE, DOC, STRING, INT or FLOAT.</returns>
		///</summary>
		int Type { get; }

		///<summary>
		/// Returns the Locale by which term values are interpreted.
		/// May return <code>null</code> if no Locale was specified.
		/// <returns>Locale, or <code>null</code>.</returns>
		///</summary>
		CultureInfo Locale { get; }

		///<summary>
		///Returns the instance of a <see cref="IFieldCache"></see> parser that fits to the given sort type.
		/// May return <code>null</code> if no parser was specified. Sorting is using the default parser then.
		/// <returns>
		/// An instance of a <see cref="IFieldCache"></see> parser, or <code>null</code>.
		/// </returns>
		///</summary>
		IFieldCacheParser Parser { get; }

		///<summary>
		/// Returns whether the sort should be reversed.
		/// <returns> True if natural order should be reversed.</returns>
		///</summary>
		bool Reverse { get; }

		///<summary>
		///Returns the <see cref="IFieldComparatorSource"></see> used for
		///custom sorting
		///</summary>
		IFieldComparatorSource ComparatorSource { get; }

		///<summary>
		/// Returns the <see cref="IFieldComparator"></see> to use for
		/// sorting.
		///
		/// <b>NOTE:</b> This API is experimental and might change in
		/// incompatible ways in the next release.
		///
		/// <param name="numHits"> number of top hits the queue will store</param>
		/// <param name="sortPos"> position of this SortField within {@link
		///   Sort}.  The comparator is primary if sortPos==0,
		///   secondary if sortPos==1, etc.  Some comparators can
		///   optimize themselves when they are the primary sort.
		/// </param>
		/// <returns><see cref="IFieldComparator"></see> to use when sorting
		/// </returns>
		///</summary>
		IFieldComparator GetComparator(int numHits, int sortPos);
	}
}